<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<title>Using Dialogs</title>
<meta name="generator" content="Oracle DARB XHTML Converter (Mode = document) - Version 5.1.2 Build 015" />
<meta name="date" content="2011-11-03T11:27:21Z" />
<meta name="robots" content="noarchive" />
<meta name="doctitle" content="Using Dialogs" />
<meta name="relnum" content="Release 1.5" />
<meta name="partnum" content="E23376-02" />
<link rel="copyright" href="./dcommon/html/cpyr.htm" title="Copyright" type="text/html" />
<link rel="stylesheet" href="./dcommon/css/blafdoc.css" title="Oracle BLAFDoc" type="text/css" />
<link rel="contents" href="toc.htm" title="Contents" type="text/html" />
<link rel="index" href="index.htm" title="Index" type="text/html" />
<link rel="prev" href="tabletree.htm" title="Previous" type="text/html" />
<link rel="next" href="layout.htm" title="Next" type="text/html" />
</head>
<body>
<div class="header"><a id="top" name="top"></a>
<div class="zz-skip-header"><a href="#BEGIN">Skip Headers</a></div>
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<tr>
<td align="left" valign="top"><b>Lightweight UI Toolkit Developer's Guide</b><br />
<b>Release 1.5</b><br />
E23376-02</td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<tr>
<td align="center"><a href="tabletree.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="layout.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
<td>&nbsp;</td>
</tr>
</table>
<a name="BEGIN" id="BEGIN"></a></div>
<!-- class="header" -->
<div class="ind"><!-- End Header --><a id="CEHBCCIJ" name="CEHBCCIJ"></a>
<h1 class="chapter"><span class="secnum">5</span> Using Dialogs</h1>
<p>A Dialog is a form that occupies a part of the screen as a top level component. By default dialogs always appear as a modal entity to the user. Modality indicates that a dialog blocks the calling thread even if the calling thread is the <span class="italic">Event Dispatcher Thread</span> (<a id="sthref94" name="sthref94"></a>EDT). Dialogs allow us to prompt users for information and rely on the information being returned as a response after the dialog <code>show</code> method. Each <a id="sthref95" name="sthref95"></a>Dialog has a body that is located in the center of the dialog. The Body can contain a component, so you can use your own customer component or pre-built container.</p>
<div align="center">
<div class="inftblnote"><br />
<table class="Note oac_no_warn" summary="" border="1" width="80%" frame="hsides" rules="groups" cellpadding="3" cellspacing="0">
<tbody>
<tr>
<td align="left">
<p class="notep1">Note:</p>
A modal dialog does not release the block until a <a id="sthref96" name="sthref96"></a>dispose method is called. For example, calling <code>show()</code> from another form does not release the block.</td>
</tr>
</tbody>
</table>
<br /></div>
<!-- class="inftblnote" --></div>
<a id="Z400087f1290622" name="Z400087f1290622"></a>
<div class="sect1">
<h2 class="sect1">Dialog Types</h2>
<p>For better user experience, dialogs have five types of alerts. The alert <a id="sthref97" name="sthref97"></a>type indicates a sound to play or an icon to display if none is explicitly set:</p>
<ul>
<li>
<p>ALARM</p>
</li>
<li>
<p>CONFIRMATION</p>
</li>
<li>
<p>ERROR</p>
</li>
<li>
<p>INFO</p>
</li>
<li>
<p>WARNING</p>
</li>
</ul>
<p>By default the alerts are set to play the device alert sounds.</p>
<p>Icons are not currently provided by default, but you can manually add them to customized dialogs. Icons can be used to indicate the alert state, similar to JDialog icons in Swing. See http://java.sun.com/docs/books/tutorial/uiswing/components/dialog.html (<code><a href="http://java.sun.com/docs/books/tutorial/uiswing/components/dialog.html">http://java.sun.com/docs/books/tutorial/uiswing/components/dialog.html</a></code>).</p>
</div>
<!-- class="sect1" -->
<a id="Z400087f1290630" name="Z400087f1290630"></a>
<div class="sect1">
<h2 class="sect1">Creating a Dialog</h2>
<p>To create and show a dialog you can do the following:</p>
<ul>
<li>
<p>Create and show the dialog using one of the static show methods.</p>
</li>
<li>
<p>Use <code>new Dialog()</code> and invoke its <code>show()</code> method. The static methods are only helpers.</p>
</li>
</ul>
<p>The arguments to all of the show methods are standardized, though the number of arguments for each method varies. The static show methods provide support for laying out standard dialogs, providing icons, specifying the dialog title and text, and customizing the button text.</p>
<p>The following list describes each argument. To see the exact list of arguments for a particular method, see the Dialog API in the API documentation located in <span class="italic">install-dir</span><code>/docs/api/lwuit</code>.</p>
<ul>
<li>
<p><code>String</code> <span class="italic">title</span></p>
<p>The title of the dialog.</p>
</li>
<li>
<p><code>Component</code> <span class="italic">body</span></p>
<p>Component placed in the center of the dialog. This component can be a container that contains other components.</p>
</li>
<li>
<p><code>String</code> <span class="italic">text</span></p>
<p>The text displayed in the dialog which can be used instead of Body.</p>
</li>
<li>
<p><code>Command[]</code> <span class="italic">cmds</span></p>
<p>Array of commands that are added to the dialog. Any click on any command disposes of the dialog. Examples of commands are OK and Cancel.</p>
</li>
<li>
<p><code>int</code> <span class="italic">type</span></p>
<p>The type of the alert can be one of TYPE_WARNING, TYPE_INFO, TYPE_ERROR, TYPE_CONFIRMATION or TYPE_ALARM to indicate the sound to play or an icon to display.</p>
</li>
<li>
<p><code>Image</code> <span class="italic">icon</span></p>
<p>The icon to display in the dialog.</p>
</li>
<li>
<p><code>long</code> <span class="italic">timeout</span></p>
<p>A timeout in milliseconds, after which the dialog closes and null is returned. If time-out value is 0, the dialog remains open indefinitely, until its dispose method is invoked.</p>
</li>
<li>
<p><code>Transition</code> <span class="italic">transition</span></p>
<p>The transition installed when the dialog enters and leaves the screen. For more information see <a href="transitions.htm#Z40006f61289435">Transition</a>.</p>
</li>
<li>
<p><code>String</code> <span class="italic">okText</span></p>
<p>The text to appear in the command dismissing the dialog.</p>
</li>
<li>
<p><code>String</code> <span class="italic">cancelText</span></p>
<p>Optionally null for a text to appear in the cancel command for canceling the dialog.</p>
</li>
<li>
<p><code>int</code> <span class="italic">top</span></p>
<p>Inset in pixels between the top of the screen and the form.</p>
</li>
<li>
<p><code>int</code> <span class="italic">bottom</span></p>
<p>Inset in pixels between the bottom of the screen and the form.</p>
</li>
<li>
<p><code>int</code> <span class="italic">left</span></p>
<p>Inset in pixels between the left of the screen and the form.</p>
</li>
<li>
<p><code>int</code> <span class="italic">right</span></p>
<p>Inset in pixels between the right of the screen and the form.</p>
</li>
<li>
<p><code>boolean</code> <span class="italic">includeTitle</span></p>
<p>Whether the title should hang in the top of the screen or be glued onto the dialog content pane.</p>
</li>
</ul>
<a id="Z400087f1290586" name="Z400087f1290586"></a>
<div class="sect2">
<h3 class="sect2">Return Types of Show Methods</h3>
<p>You can use one of three convenient return value show methods: void, Command, or boolean.</p>
<ul>
<li>
<p>Command returns the command object the user clicked. See the Command API in the API documentation found in <span class="italic">install-dir</span><code>/docs/api/lwuit</code>.</p>
</li>
<li>
<p>The boolean value of true is returned when the OK command is pressed or if <code>cancelText</code> is null (meaning there is no cancel command text visible). It is false otherwise.</p>
</li>
</ul>
</div>
<!-- class="sect2" -->
<a id="CEHHEJJH" name="CEHHEJJH"></a>
<div class="sect2">
<h3 class="sect2">Non-Static Show Methods</h3>
<p>The dialog API provides two non-static methods to create two more types of dialogs.</p>
<p>The first method takes no arguments and produces a dialog without any commands. The only way to close such a dialog is to invoke the <a id="sthref98" name="sthref98"></a><code>dispose()</code> method on the dialog. Since the dialog is blocking, meaning once the dialog is displayed its calling thread can not proceed until it is closed, the call to <code>dispose</code> must be made from a different thread. To do this, schedule the call to <code>dispose</code> with a timer thread. Note that the timer thread must be started before the dialog is displayed. This approach is referred to as an auto-closing dialog.</p>
<p>The second dialog type has five parameters. The first four are the four wing insets (top, bottom, left, and right) and the fifth parameter determines whether to include the Dialog title assigned through the dialog constructor (see <a href="#Z40006f01291451">Figure 5-1</a>).</p>
<p><code>// Call show with inset parameters</code></p>
<p><code>dialog.show(90, 90, 10, 10, true);</code></p>
</div>
<!-- class="sect2" -->
<a id="Z400087f1290605" name="Z400087f1290605"></a>
<div class="sect2">
<h3 class="sect2">Using the <code>dispose()</code> Method</h3>
<p>The <a id="sthref99" name="sthref99"></a>dispose methods closes the current dialog and returns to the parent form. When <code>show()</code> is used without arguments, one way to close the dialog is to set a timer to call <code>dispose</code> just before calling the <code>show</code> method (otherwise the dispose method is never performed).</p>
</div>
<!-- class="sect2" -->
<a id="Z400087f1290616" name="Z400087f1290616"></a>
<div class="sect2">
<h3 class="sect2">Getting the User's Input from a Dialog</h3>
<p>As mentioned in <a href="#CEHHEJJH">Non-Static Show Methods</a>, return value types can be either Command or a boolean value. For example, if a user has a dialog with two commands, Approve and Decline, the user clicks and the selected command is returned. For the boolean return type, a true or false value indicates whether the user clicked the OK command.</p>
<div class="figure"><a id="Z40006f01291451" name="Z40006f01291451"></a>
<p class="titleinfigure">Figure 5-1 Typical Dialogs</p>
<img src="img/dialogs.jpg" alt="Description of Figure 5-1 follows" title="Description of Figure 5-1 follows" longdesc="img_text/dialogs.htm" /><br />
<a id="sthref100" name="sthref100" href="img_text/dialogs.htm">Description of "Figure 5-1 Typical Dialogs"</a><br />
<br /></div>
<!-- class="figure" --></div>
<!-- class="sect2" --></div>
<!-- class="sect1" --></div>
<!-- class="ind" -->
<!-- Start Footer -->
<div class="footer">
<hr />
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100%">
<col width="33%" />
<col width="*" />
<col width="33%" />
<tr>
<td valign="bottom">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="100">
<col width="*" />
<col width="48%" />
<col width="48%" />
<tr>
<td>&nbsp;</td>
<td align="center"><a href="tabletree.htm"><img src="./dcommon/gifs/leftnav.gif" alt="Previous" /><br />
<span class="icon">Previous</span></a>&nbsp;</td>
<td align="center"><a href="layout.htm"><img src="./dcommon/gifs/rightnav.gif" alt="Next" /><br />
<span class="icon">Next</span></a></td>
</tr>
</table>
</td>
<td class="copyrightlogo"><img class="copyrightlogo" src="./dcommon/gifs/oracle.gif" alt="Oracle Logo" /><br />
<span class="copyrightlogo">Copyright&nbsp;&copy;&nbsp;2008, 2011,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</span> <a href="./dcommon/html/cpyr.htm"><br />
<span class="copyrightlogo">Legal Notices</span></a></td>
<td valign="bottom" align="right">
<table class="simple oac_no_warn" summary="" cellspacing="0" cellpadding="0" width="225">
<tr>
<td>&nbsp;</td>
<td align="center" valign="top"><a href="toc.htm"><img src="./dcommon/gifs/toc.gif" alt="Go To Table Of Contents" /><br />
<span class="icon">Contents</span></a></td>
<td align="center" valign="top"><a href="index.htm"><img src="./dcommon/gifs/index.gif" alt="Go To Index" /><br />
<span class="icon">Index</span></a></td>
</tr>
</table>
</td>
</tr>
</table>
</div>
<!-- class="footer" -->
</body>
</html>
